HttpErrorsSection Class [IIS 7 and higher]

Article
07/13/2012

Configures HTTP error handling for a Web server.

Syntax

class HttpErrorsSection : ConfigurationSectionWithCollection

Methods

The following table lists the methods exposed by the HttpErrorsSection class.

Name	Description
Add	(Inherited from ConfigurationSectionWithCollection.)
Clear	(Inherited from ConfigurationSectionWithCollection.)
Get	(Inherited from ConfigurationSectionWithCollection.)
GetAllowDefinition	(Inherited from ConfigurationSection.)
GetAllowLocation	(Inherited from ConfigurationSection.)
Remove	(Inherited from ConfigurationSectionWithCollection.)
RevertToParent	(Inherited from ConfigurationSection.)
SetAllowDefinition	(Inherited from ConfigurationSection.)
SetAllowLocation	(Inherited from ConfigurationSection.)

Properties

The following table lists the properties exposed by the HttpErrorsSection class.

Name	Description
DefaultPath	An optional string value that contains the default path of an HTTP error file or URL. When nonempty, this value is inherited by the Path property of newly created HttpErrorElement objects.
DefaultResponseMode	An optional sint32 value that configures the default response to HTTP errors. When nonempty, this value is inherited by the ResponseMode property of newly created HttpErrorElement objects. The possible values are listed later in the Remarks section.
DetailedMoreInformationLink	An optional read/write string value that specifies the URL for a link, shown at the bottom of the page, to a page with more detailed information about the error that was raised. The status, substatus, hresult, and messageid of the error are sent as part of the query string. You can use this property to point end users to a custom location for error information. The default is "https://go.microsoft.com/fwlink/?LinkID=62293".
ErrorMode	A read/write sint32 enumeration that specifies whether the detailed error functionality is enabled, disabled, or shown only to local clients. The possible values are listed later in the Remarks section.
ExistingResponse	A read/write sint32 enumeration that specifies how IIS handles existing custom errors. The possible values are listed later in the Remarks section.
HttpErrors	An array of HttpErrorElement values that configure handling for specific HTTP errors.
Location	(Inherited from ConfigurationSection.) A key property.
Path	(Inherited from ConfigurationSection.) A key property.
SectionInformation	(Inherited from ConfigurationSection.)

Subclasses

This class contains no subclasses.

Remarks

This class exposes the settings in the <httpErrors> section of a configuration file.

The custom errors represented by the HttpErrorsSection class are related to IIS 7 and are in the System.WebServer.Configuration namespace. Each of these errors is represented by an instance of the HttpErrorElement class.

The custom errors represented by the CustomErrorsSection class are specific to ASP.NET and are in the System.Web namespace. Each of these errors is represented by an instance of the CustomError class.

The following table lists the possible values for the DefaultResponseMode property. The default is 0 (File).

Value	Keyword	Description
0	File	The Web server returns the Web page from the static file specified in the Path property of the HttpErrorElement class. Note: Custom errors are language-specific and typically return the custom error in the language of the client. This requires that the client's language pack is installed. The file path is constructed as follows: PrefixLanguageFilePath\ClientLanguageID\ErrorCodeFile For example, if PrefixLanguageFilePath is "d:\inetpub\custerr", the client browser sends "en-us" in the Accept-Language header, and the error code is 404, the resulting path when the en-US language pack is installed is d:\inetpub\custerr\en-us\404.htm. If ja-JP is the system language, and the en-US language pack is not installed, the resulting path is d:\inetpub\custerr\ja-jp\404.htm.
1	ExecuteURL	The Web server returns the internal ASP page specified in the Path property of the HttpErrorElement class. The URL should be in the scope of the same application pool. Note: In IIS 7, the redirection creates a URL with the following format (the items in the brackets are optional): /<CustomErrorPage>[?<QueryString>]&resourcePath=<OriginalURL>[?<OriginalQueryString>]&statusCode=<StatusCode>
2	Redirect	The Web server provides an HTTP 302 Found response and includes the URL specified in the Path property of the HttpErrorElement class in the Location field of the response. If the response is a GET method instead of a HEAD method, it should also include an entity that has a short hyperlink to the new URL. Note: In IIS 7, the redirection creates a URL with the following format (the items in the brackets are optional): /<CustomErrorPage>[?<QueryString>]&resourcePath=<OriginalURL>[?<OriginalQueryString>]&statusCode=<StatusCode>

The following table lists the possible values for the ErrorMode property. The default is 0 (DetailedLocalOnly).

Value	Keyword	Description
0	DetailedLocalOnly	A detailed error response is generated only if the request comes from the local computer. If the request comes from an external address, the server generates a custom error response. Note: The value of the ExistingResponse property determines whether a detailed or custom error is generated.
1	Custom	The error that the module or server generates is replaced by a custom page that you specify. This mode is useful in providing friendlier error messages to end users. Note: This setting turns off detailed errors, even for local requests.
2	Detailed	A page with detailed information about the application error is displayed, and custom errors are not shown. This mode is useful for testing and debugging Web sites and applications. Note: It is a security risk to set ErrorMode to Detailed, because even remote clients will receive detailed error information that could lead to unwanted information disclosure.

DetailedLocalOnly

A detailed error response is generated only if the request comes from the local computer. If the request comes from an external address, the server generates a custom error response.

Note:

The value of the ExistingResponse property determines whether a detailed or custom error is generated.

Custom

The error that the module or server generates is replaced by a custom page that you specify. This mode is useful in providing friendlier error messages to end users.

Note:

This setting turns off detailed errors, even for local requests.

Detailed

A page with detailed information about the application error is displayed, and custom errors are not shown. This mode is useful for testing and debugging Web sites and applications.

Note:

It is a security risk to set ErrorMode to Detailed, because even remote clients will receive detailed error information that could lead to unwanted information disclosure.

The following table lists the possible values for the ExistingResponse property. The default is 0 (Auto).

Value	Keyword	Description
0	Auto	The response depends on the first successful match of the following set of ordered conditions: If the IHttpResponse::SetStatus method was called by using the fTrySkipCustomErrors flag, the existing response is passed through, and no detailed or custom error is shown. If the ErrorMode property is set to Custom, the response is replaced. If ErrorMode is set to Detailed and there is an existing response, the response is passed through. If ErrorMode is set to Detailed and there is no existing response, the response is replaced with a detailed error.
1	Replace	The existing response is always replaced, regardless of how SetStatus was called.
2	PassThrough	The existing response is always used.

Auto

The response depends on the first successful match of the following set of ordered conditions:

If the IHttpResponse::SetStatus method was called by using the fTrySkipCustomErrors flag, the existing response is passed through, and no detailed or custom error is shown.
If the ErrorMode property is set to Custom, the response is replaced.
If ErrorMode is set to Detailed and there is an existing response, the response is passed through.
If ErrorMode is set to Detailed and there is no existing response, the response is replaced with a detailed error.

Replace

The existing response is always replaced, regardless of how SetStatus was called.

PassThrough

The existing response is always used.

Example

The following code example specifies new values for the DefaultPath, ErrorMode, and DetailedMoreInformationLink properties. A helper function displays the configuration section values before and after the change.

' Connect to the WMI WebAdministration namespace.
Set oWebAdmin = GetObject("winmgmts:root\WebAdministration")

' Get the HTTP errors section.
Set oSection = oWebAdmin.Get( _
    "HttpErrorsSection.Path='" & _
    "MACHINE/WEBROOT/APPHOST/',Location=''")

' Display the class name of the section.
WScript.Echo "[ " & oSection.Path_.Class & " ]"

' Display the initial values.
Call DisplayValues("Initial Values", oSection) 

' Specify the path of a default error page.
oSection.DefaultPath = _
    "D:\inetpub\custerr\en-US\contoso\DefaultErrorPage.htm"

' Specify a detailed more information link.
oSection.DetailedMoreInformationLink = "https://www.contoso.com/MoreInfo.htm"

'Set the ErrorMode property to Custom.
oSection.ErrorMode = 1

' Save the values to configuration.
oSection.Put_

' Refresh the oSection object variable with the new values.
oSection.Refresh_

' Display the changed values.
Call DisplayValues("New Values", oSection)

' ==== DisplayValues helper function. ====
Function DisplayValues(HeadingText, oSection)

    ' Display a heading.
    WScript.Echo
    WScript.Echo HeadingText
    WScript.Echo String(Len(HeadingText), "-")

    ' Display the non-embedded section properties.
    For Each prop In oSection.Properties_

        If Left( _
            Prop.Qualifiers_("CIMTYPE"), 6) _
            <> "object" then
            WScript.Echo prop.Name & ": " & prop.Value
        End If

    Next 
End Function

Inheritance Hierarchy

ConfigurationSection

ConfigurationSectionWithCollection

HttpErrorsSection

Requirements

Type	Description
Client	Requires IIS 7 on Windows Vista.
Server	Requires IIS 7 on Windows Server 2008.
Product	IIS 7
MOF file	WebAdministration.mof

HttpErrorsSection Class [IIS 7 and higher]

Syntax

Methods

Properties

Subclasses

Remarks

Example

Inheritance Hierarchy

Requirements

See Also

Reference

Additional resources